DOKS Operational Readiness, Part 3: Configure Wildcard Certificates :: DigitalOcean Documentation

DigitalOcean Kubernetes (DOKS) is a managed Kubernetes service that lets you deploy Kubernetes clusters without the complexities of handling the control plane and containerized infrastructure. Clusters are compatible with standard Kubernetes toolchains, integrate natively with DigitalOcean Load Balancers and volumes, and can be managed programmatically using the API and command line. For critical workloads, add the high-availability control plane to increase uptime with 99.95% SLA.

In the previous part of the tutorial series, you installed an NGINX ingress controller and configured the backend services. NGINX comes with self-signed TLS certificates. For live environments, you will want to enable NGINX to use production-ready TLS certificates for the backend services and automatically configure TLS certificates for your hosts. In this tutorial, the certificate issuer uses the DNS-01 challenge which supports wildcard certificates. A wildcard certificate is able to handle sub-domains as well and has global scope for the whole DNS domain you own. If you want to use HTTPS instead, you need to set up the HTTP-01 challenge, as described in Set Up NGINX Ingress Controller with HTTPS Enabled.

In this tutorial, you use Cert-Manager to set up DNS-01 challenge. Cert Manager can handle DNS TXT records for DigitalOcean using the DigitalOcean Provider. To do so, you will create a namespaced Issuer resource type, which is responsible for the ACME challenge process. The Issuer CRD also defines the required provider (DigitalOcean), to create DNS records during the DNS-01 challenge. You can find the manifests used in this tutorial in the Kubernetes-Starter-Kit-Developers GitHub repository.

The following diagram shows the setup used in this tutorial:

The user creates the Issuer and certificate CRDs. Then, Cert-Manager initiates the DNS-01 challenge. Let’s Encrypt asks Cert-Manager to complete the DNS-01 challenge, which Cert-Manager completes using the DigitalOcean DNS-01 solver. After the process finishes successfully, Let’s Encrypt issues a valid TLS certificate. Then, Cert-Manager creates the Kubernetes secret that contains the TLS certificate data, which is used by NGINX.

After finishing this tutorial, you will be able to:

Create an Issuer resource type, which is responsible for the ACME challenge process. The Issuer CRD also defines the required provider (such as DigitalOcean), to create DNS records during the DNS-01 challenge.

Create a certificate resource type which makes use of the Issuer CRD to obtain a valid certificate from the Certificate Authority (CA). The certificate CRD also defines what Kubernetes Secret to create and store the final certificate after the DNS-01 challenge completes successfully.

Configure NGINX to consume the secret, and use the wildcard certificate to enable TLS encryption for your entire domain.

NGINX comes with self-signed TLS certificates but for live environments, you may want to enable NGINX to use production-ready TLS certificates. In this step, you will install Cert-Manager 1-Click, and then configure it to issue Let’s Encrypt certificates. Certificate renewals happen automatically via Cert-Manager.

Navigate to your cluster in the Kubernetes section of the control panel, then click on the Marketplace tab. In the recommended apps section, select Cert-Manager and click Install.

When installed, the app appears in the History of Installed 1-Click Apps section of the tab.

Inspect the Kubernetes resources created by Cert-Manager:

The output looks similar to the following:

Note that the cert-manager pods and webhook service are running.

Cert-Manager creates Custom Resource Defintions (CRDs). Cert-Manager relies on three important CRDs to issue certificates from a Certificate Authority (such as Let’s Encrypt):

Issuer: Defines a namespaced certificate issuer, which allows you to use different CAs in each namespace.

ClusterIssuer: Similar to Issuer, but it does not belong to a namespace and can be used to issue certificates in any namespace.

Certificate: Defines a namespaced resource that references an Issuer or ClusterIssuer for issuing certificates.

Inspect the CRDs by running the following command:

The output looks similar to the following:

Create a Kubernetes secret for the DigitalOcean Provider that Cert-Manager is going to use to perform the DNS-01 challenge. The secret must contain your DigitalOcean API token, which the provider needs to create DNS records on your behalf during the DNS-01 challenge. This step is required so that the CA knows that the domain in question is really owned by you.

Create the Kubernetes secret containing the DigitalOcean API token, using the same namespace where you deployed your Ingress Controller. In this example, we use backend.

DigitalOCean Provider uses the Kubernetes secret and Cert-Manager performs the DNS-01 challenge.

The Issuer CRD is responsible for solving the DNS-01 challenge. Create the following YAML file for the Issuer manifest and save it as cert-manager-wcard-issuer.yaml. This example uses backend as the namespace. Use your namespace in your manifest:

The ACME issuer configuration has the following fields:

Enter your email address and save the file.

Create the Issuer resource using the following command:

Verify that the Issuer resource is created:

The output looks like the following:

Note that the READY column says True. You can use kubectl describe issuer letsencrypt-dev-wcard -n backend to get more details about the Issuer resource.

Create a certificate resource that will make use of the previously created Issuer. The Issuer contacts Let’s Encrypt (via REST API) and starts the DNS-01 challenge. During the process, Let’s Encrypt will try to create a TXT record using your domain to make sure that you really are the owner. The DNS TXT records manipulation happens via the DigitalOcean REST API (you configured a Kubernetes secret containing the DO API token earlier for this purpose). After successfully creating and retrieving the DNS record, Let’s Encrypt will issue a production ready TLS certificate that you can use in your environment.

Create the following YAML file for the certificate manifest and save it as cert-manager-wcard-issuer.yaml. This example uses doks-starter-kit.page as the domain and backend as the namespace. Use your domain and namespace in your manifest:

The YAML file has the following fields:

namespace: Cert-Manager will put the resulting secret in the same Kubernetes namespace as the certificate.

secretName: Secret name to create, where the private key and certificate should be stored.

issuerRef: The Issuer to use for getting the certificate.

commonName: Common name to be used on the certificate.

dnsNames: List of DNS Subject Alternative Names (SAN) to be set on the certificate.

Next, create the certificate resource in your DOKS cluster:

Verify the certificate status:

It can take a few minutes for the process to complete. The output looks similar to the following:

Notice that the READY column value is True, and the SECRET name matches the name you specified in the manifest. If you see False in the READY column, use kubectl logs -l app=cert-manager,app.kubernetes.io/component=controller -n cert-manager to view the logs to troubleshoot.

Finally, you can verify the Kubernetes secret which contains your TLS certificate

The output looks similar to the following:

Having a certificate configured and working, ensures that the wildcard TLS certificate is always available for your ingress resources to use. The wildcard certificate will be renewed automatically before it expires.

Create the following manifest to configure NGINX to use a wildcard certificate and save it as wildcard-host.yaml. This example uses doks-starter-kit.page and backend. Use your domain name and namespace in the manifest:

The manifest has the following fields:

hosts: Because a wildcard certificate is available, you can use wildcards to match all hosts for a specific domain (e.g.: *.doks-starter-kit.page).

secretName: Reference to Kubernetes secret containing your wildcard TLS certificate.

Create the NGINX ingress resource:

If you have two rules with / as the path, NGINX does not know which one to use and therefore the deployment fails. To workaround this, add different paths for each service. For example, path: /echo/?(.*) instead of path: /.

Check that the resource is created:

The output looks similar to the following:

Finally, test the NGINX setup using curl (or type https://echo. in a Web browser) for each backend service.

Notice that you receive a redirect to use HTTPS instead and that the certificate is a wildcard one.

In this tutorial, you configured Cert-Manager to use wildcard certificates for your entire domain using DNS-01 challenge.

You can use additional 1-Click apps such as Prometheus for monitoring your cluster, or TrilioVault or Velero for backing up and restoring your cluster.